Parent | Child | Previous | Next
 
Xbasic

SQL::ArgumentsSet Method

Syntax

Result_Flag as L = Set(Name as C, Value as A [, Usage as SQL::ArgumentUsage [,IsNull as L = .f.]])

Arguments

NameCharacter

The unique name property of an argument. See the SQL::Argument class.

ValueAny Type

The data may be a simple data type (listed below), a character array, or a numeric array.

  • "Blob"
  • "Character"
  • "Date"
  • "Logical"
  • "Numeric"
  • "Short Time"
  • "Time"
UsageSQL::ArgumentUsage

Defines how the argument should be used. See SQL::ArgumentUsage Enumerated Type for more information.

IsNullLogical

Default value is .f.. Can be used to set the value of the argument to NULL. See also SQL::Arguments SetNull Function.

Description

Set the value and (optionally) the usage of an argument.

Discussion

The Set() method adds or redefines an argument's value. You can optionally specify the usage of the argument if the argument is NULL. Returns true (.t.) if the operation is successful and false (.f.) if it fails.

Example

dim args as SQL::Arguments
args.add("state", "MA")
? args.Find("state")
= "MA"

? args.set("state", "NH")
= .T.

? args.Find("state")
= "NH"

Setting an Argument to NULL

This example demonstrates using Set() to add a NULL argument:

dim args as SQL::Arguments
args.set("nullValue", "", SQL::ArgumentUsage::InputArgument, .t.)

? args.find("nullValue").IsNull
= .T.

Filtering a SQL Query with Arguments Using Set

This script prompts for a value, then returns a filtered list of records.

dim conn as SQL::Connection
dim sql as C
dim vCity as C
dim args as SQL::Arguments

vCity = ui_get_text("City", "Show Customers in what city?")
sql = "select customername from customers where city = :city Order By CustomerID"

if .not. conn.open("::Name::AADemo-Northwind")
    ui_msg_box("Error", conn.CallResult.text)
    end
end if

if .not. args.Set("city", vCity)
    end
end if

if .not. conn.execute(sql, args)
    ui_msg_box("Error", conn.CallResult.text)
    end
end if

sql_resultset_preview(conn.resultset)
images/add1.png
Results after searching for "Spain".
The ui_msg_box and sql_resultset_preview functions are only available in desktop applications.

Setting an Argument Array

An argument can be an array of values. Array arguments are often used with IN clauses. For example, in the code below an array argument is used to get a list of records with a CustomerID that matches one of the following values: "ALFKI", "BOLID", "FRANK", or "OCEAN". The resulting query is returned as JSON and displayed using showvarjson()

dim sql as c = "SELECT CustomerID, CompanyName FROM Customers WHERE CustomerID IN (:what_customers)"
dim args as SQL::Arguments
dim customers[0] as C
customers.push("ALFKI")
customers.push("BOLID")
customers.push("FRANK")
customers.push("OCEAN")

args.set("what_customers",customers)

dim cn as SQL::Connection
if (cn.open("::Name::AADemo-Northwind")) then
	dim JSON as C
	JSON = cn.toJSON(sql,args)
	showvarjson(JSON)
	cn.close()
end if

Here is the JSON returned by the query:

[
    {
        "CustomerID": "ALFKI",
        "CompanyName": "Alfreds Futterkiste"
    },
    {
        "CustomerID": "BOLID",
        "CompanyName": "Bólido Comidas preparadas"
    },
    {
        "CustomerID": "FRANK",
        "CompanyName": "Frankenversand"
    },
    {
        "CustomerID": "OCEAN",
        "CompanyName": "Océano Atlántico Ltda."
    }
]

See Also